<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <meta name="author" content="PG-Strom Development Team">
  <link rel="shortcut icon" href="../img/favicon.ico">
  <title>Arrow_fdw - PG-Strom Manual</title>
  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

  <link rel="stylesheet" href="../css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css">
  <link href="//fonts.googleapis.com/earlyaccess/notosansjp.css" rel="stylesheet">
  <link href="//fonts.googleapis.com/css?family=Open+Sans:600,800" rel="stylesheet">
  <link href="../custom.css" rel="stylesheet">
  
  <script>
    // Current page data
    var mkdocs_page_name = "Arrow_fdw";
    var mkdocs_page_input_path = "arrow_fdw.md";
    var mkdocs_page_url = null;
  </script>
  
  <script src="../js/jquery-2.1.1.min.js" defer></script>
  <script src="../js/modernizr-2.8.3.min.js" defer></script>
  <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
  <script>hljs.initHighlightingOnLoad();</script> 
  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
        <a href=".." class="icon icon-home"> PG-Strom Manual</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
  </form>

  [<strong>Japanese</strong> | <a href="../.." style="color: #cccccc">English</a>]

</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
	<ul class="current">
	  
          
            <li class="toctree-l1">
		
    <a class="" href="..">はじめに</a>
	    </li>
          
            <li class="toctree-l1">
		
    <a class="" href="../install/">インストール</a>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">利用ガイド</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../operations/">基本的な操作</a>
                </li>
                <li class="">
                    
    <a class="" href="../sys_admin/">システム管理</a>
                </li>
                <li class="">
                    
    <a class="" href="../brin/">インデックス対応</a>
                </li>
                <li class="">
                    
    <a class="" href="../partition/">パーティション</a>
                </li>
                <li class="">
                    
    <a class="" href="../troubles/">トラブルシューティング</a>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">先進機能</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../ssd2gpu/">SSDtoGPUダイレクトSQL</a>
                </li>
                <li class=" current">
                    
    <a class="current" href="./">Arrow_fdw</a>
    <ul class="subnav">
            
    <li class="toctree-l3"><a href="#_1">概要</a></li>
    
        <ul>
        
            <li><a class="toctree-l4" href="#apache-arrow">Apache Arrowとは</a></li>
        
        </ul>
    

    <li class="toctree-l3"><a href="#_2">運用</a></li>
    
        <ul>
        
            <li><a class="toctree-l4" href="#_3">外部テーブルの定義</a></li>
        
            <li><a class="toctree-l4" href="#_4">外部テーブルオプション</a></li>
        
            <li><a class="toctree-l4" href="#_5">データ型の対応</a></li>
        
            <li><a class="toctree-l4" href="#explain">EXPLAIN出力の読み方</a></li>
        
        </ul>
    

    <li class="toctree-l3"><a href="#arrow">Arrowファイルの作成方法</a></li>
    
        <ul>
        
            <li><a class="toctree-l4" href="#pyarrowpandas">PyArrow+Pandas</a></li>
        
            <li><a class="toctree-l4" href="#pg2arrow">Pg2Arrow</a></li>
        
        </ul>
    

    <li class="toctree-l3"><a href="#_6">先進的な使い方</a></li>
    
        <ul>
        
            <li><a class="toctree-l4" href="#ssdtogpusql">SSDtoGPUダイレクトSQL</a></li>
        
            <li><a class="toctree-l4" href="#_7">パーティション設定</a></li>
        
        </ul>
    

    </ul>
                </li>
                <li class="">
                    
    <a class="" href="../gstore_fdw/">Gstore_fdw</a>
                </li>
                <li class="">
                    
    <a class="" href="../plcuda/">PL/CUDA</a>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">リファレンス</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../ref_types/">データ型</a>
                </li>
                <li class="">
                    
    <a class="" href="../ref_devfuncs/">関数と演算子</a>
                </li>
                <li class="">
                    
    <a class="" href="../ref_sqlfuncs/">SQLオブジェクト</a>
                </li>
                <li class="">
                    
    <a class="" href="../ref_params/">GUCパラメータ</a>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <a class="" href="../release_note/">リリースノート</a>
	    </li>
          
        </ul>
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="..">PG-Strom Manual</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="..">Docs</a> &raquo;</li>
    
      
        
          <li>先進機能 &raquo;</li>
        
      
    
    <li>Arrow_fdw</li>
    <li class="wy-breadcrumbs-aside">
      
    </li>
  </ul>
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1>列指向データストア (Arrow_Fdw)</h1>

<h1 id="_1">概要</h1>
<p>PostgreSQLのテーブルは内部的に8KBのブロック<sup id="fnref:1"><a class="footnote-ref" href="#fn:1" rel="footnote">1</a></sup>と呼ばれる単位で編成され、ブロックは全ての属性及びメタデータを含むタプルと呼ばれるデータ構造を行単位で格納します。行を構成するデータが近傍に存在するため、これはINSERTやUPDATEの多いワークロードに有効ですが、一方で大量データの集計・解析ワークロードには不向きであるとされています。</p>
<p>通常、大量データの集計においてはテーブル内の全ての列を参照する事は珍しく、多くの場合には一部の列だけを参照するといった処理になりがちです。この場合、実際には参照されない列のデータをストレージからロードするために消費されるI/Oの帯域は全く無駄ですが、行単位で編成されたデータに対して特定の列だけを取り出すという操作は困難です。</p>
<p>逆に列単位でデータを編成した場合、INSERTやUPDATEの多いワークロードに対しては極端に不利ですが、大量データの集計・解析を行う際には被参照列だけをストレージからロードする事が可能になるため、I/Oの帯域を最大限に活用する事が可能です。 またプロセッサの処理効率の観点からも、列単位に編成されたデータは単純な配列であるかのように見えるため、GPUにとってはCoalesced Memory Accessというメモリバスの性能を最大限に引き出すアクセスパターンとなる事が期待できます。</p>
<p><img alt="Row/Column data structure" src="../img/row_column_structure.png" /></p>
<h2 id="apache-arrow">Apache Arrowとは</h2>
<p>Apache Arrowとは、構造化データを列形式で記録、交換するためのデータフォーマットです。 主にビッグデータ処理のためのアプリケーションソフトウェアが対応しているほか、CやC++、Pythonなどプログラミング言語向けのライブラリが整備されているため、自作のアプリケーションからApache Arrow形式を扱うよう設計する事も容易です。</p>
<p><img alt="Row/Column data structure" src="../img/arrow_shared_memory.png" /></p>
<p>Apache Arrow形式ファイルの内部には、データ構造を定義するスキーマ（Schema）部分と、スキーマに基づいて列データを記録する1個以上のレコードバッチ（RecordBatch）部分が存在します。データ型としては、整数や文字列（可変長）、日付時刻型などに対応しており、個々の列データはこれらデータ型に応じた内部表現を持っています。</p>
<p>Apache Arrow形式におけるデータ表現は、必ずしも全ての場合でPostgreSQLのデータ表現と一致している訳ではありません。例えば、Arrow形式ではタイムスタンプ型のエポックは<code>1970-01-01</code>で複数の精度を持つ事ができますが、PostgreSQLのエポックは<code>2001-01-01</code>でマイクロ秒の精度を持ちます。</p>
<p>Arrow_Fdwは外部テーブルを用いてApache Arrow形式ファイルをPostgreSQL上で読み出す事を可能にします。例えば、列ごとに100万件の列データが存在するレコードバッチを8個内包するArrow形式ファイルをArrow_Fdwを用いてマップした場合、この外部テーブルを介してArrowファイル上の800万件のデータへアクセスする事ができるようになります。</p>
<h1 id="_2">運用</h1>
<h2 id="_3">外部テーブルの定義</h2>
<p>通常、外部テーブルを作成するには以下の3ステップが必要です。</p>
<ul>
<li><code>CREATE FOREIGN DATA WRAPPER</code>コマンドにより外部データラッパを定義する</li>
<li><code>CREATE SERVER</code>コマンドにより外部サーバを定義する</li>
<li><code>CREATE FOREIGN TABLE</code>コマンドにより外部テーブルを定義する</li>
</ul>
<p>このうち、最初の2ステップは<code>CREATE EXTENSION pg_strom</code>コマンドの実行に含まれており、個別に実行が必要なのは最後の<code>CREATE FOREIGN TABLE</code>のみです。</p>
<pre><code>CREATE FOREIGN TABLE flogdata (
    ts        timestamp,
    sensor_id int,
    signal1   smallint,
    signal2   smallint,
    signal3   smallint,
    signal4   smallint,
) SERVER arrow_fdw
  OPTIONS (file '/path/to/logdata.arrow');
</code></pre>

<p><code>CREATE FOREIGN TABLE</code>構文で指定した列のデータ型は、マップするArrow形式ファイルのスキーマ定義と厳密に一致している必要があります。</p>
<p>これ以外にも、Arrow_Fdwは<code>IMPORT FOREIGN SCHEMA</code>構文を用いた便利な方法に対応しています。これは、Arrow形式ファイルの持つスキーマ情報を利用して、自動的にテーブル定義を生成するというものです。 以下のように、外部テーブル名とインポート先のスキーマ、およびOPTION句でArrow形式ファイルのパスを指定します。 Arrowファイルのスキーマ定義には、列ごとのデータ型と列名（オプション）が含まれており、これを用いて外部テーブルの定義を行います。</p>
<pre><code>IMPORT FOREIGN SCHEMA flogdata
  FROM SERVER arrow_fdw
  INTO public
OPTIONS (file '/path/to/logdata.arrow');
</code></pre>

<h2 id="_4">外部テーブルオプション</h2>
<p>Arrow_Fdwは以下のオプションに対応しています。現状、全てのオプションは外部テーブルに対して指定するものです。</p>
<table>
<thead>
<tr>
<th align="left">対象</th>
<th align="left">オプション</th>
<th align="left">説明</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">外部テーブル</td>
<td align="left"><code>file</code></td>
<td align="left">外部テーブルにマップするArrowファイルを1個指定します。</td>
</tr>
<tr>
<td align="left">外部テーブル</td>
<td align="left"><code>files</code></td>
<td align="left">外部テーブルにマップするArrowファイルをカンマ(,）区切りで複数指定します。</td>
</tr>
<tr>
<td align="left">外部テーブル</td>
<td align="left"><code>dir</code></td>
<td align="left">指定したディレクトリに格納されている全てのファイルを外部テーブルにマップします。</td>
</tr>
<tr>
<td align="left">外部テーブル</td>
<td align="left"><code>suffix</code></td>
<td align="left"><code>dir</code>オプションの指定時、例えば<code>.arrow</code>など、特定の接尾句を持つファイルだけをマップします。</td>
</tr>
</tbody>
</table>
<h2 id="_5">データ型の対応</h2>
<p>Arrow形式のデータ型と、PostgreSQLのデータ型は以下のように対応しています。</p>
<table>
<thead>
<tr>
<th align="left">Arrowデータ型</th>
<th align="left">PostgreSQLデータ型</th>
<th align="left">備考</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>Int</code></td>
<td align="left"><code>int2,int4,int8</code></td>
<td align="left"><code>is_signed</code>属性は無視。<code>bitWidth</code>属性は16、32または64のみ対応。</td>
</tr>
<tr>
<td align="left"><code>FloatingPoint</code></td>
<td align="left"><code>float2,float4,float8</code></td>
<td align="left"><code>float2</code>はPG-Stromによる独自拡張</td>
</tr>
<tr>
<td align="left"><code>Binary</code></td>
<td align="left"><code>bytea</code></td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>Utf8</code></td>
<td align="left"><code>text</code></td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>Decimal</code></td>
<td align="left">`numeric</td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>Date</code></td>
<td align="left"><code>date</code></td>
<td align="left"><code>unitsz=Day</code>相当に補正</td>
</tr>
<tr>
<td align="left"><code>Time</code></td>
<td align="left"><code>time</code></td>
<td align="left"><code>unitsz=MicroSecond</code>相当に補正</td>
</tr>
<tr>
<td align="left"><code>Timestamp</code></td>
<td align="left"><code>timestamp</code></td>
<td align="left"><code>unitsz=MicroSecond</code>相当に補正</td>
</tr>
<tr>
<td align="left"><code>Interval</code></td>
<td align="left"><code>interval</code></td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>List</code></td>
<td align="left">配列型</td>
<td align="left">1次元配列のみ対応（予定）</td>
</tr>
<tr>
<td align="left"><code>Struct</code></td>
<td align="left">複合型</td>
<td align="left">対応する複合型を予め定義しておくこと。</td>
</tr>
<tr>
<td align="left"><code>Union</code></td>
<td align="left">--------</td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>FixedSizeBinary</code></td>
<td align="left"><code>char(n)</code></td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>FixedSizeList</code></td>
<td align="left">--------</td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><code>Map</code></td>
<td align="left">--------</td>
<td align="left"></td>
</tr>
</tbody>
</table>
<h2 id="explain">EXPLAIN出力の読み方</h2>
<p><code>EXPLAIN</code>コマンドを用いて、Arrow形式ファイルの読み出しに関する情報を出力する事ができます。</p>
<p>以下の例は、約309GBの大きさを持つArrow形式ファイルをマップしたflineorder外部テーブルを含むクエリ実行計画の出力です。</p>
<pre><code>=# EXPLAIN
    SELECT sum(lo_extendedprice*lo_discount) as revenue
      FROM flineorder,date1
     WHERE lo_orderdate = d_datekey
       AND d_year = 1993
       AND lo_discount between 1 and 3
       AND lo_quantity &lt; 25;
                                             QUERY PLAN
-----------------------------------------------------------------------------------------------------
 Aggregate  (cost=12632759.02..12632759.03 rows=1 width=32)
   -&gt;  Custom Scan (GpuPreAgg)  (cost=12632754.43..12632757.49 rows=204 width=8)
         Reduction: NoGroup
         Combined GpuJoin: enabled
         GPU Preference: GPU0 (Tesla V100-PCIE-16GB)
         -&gt;  Custom Scan (GpuJoin) on flineorder  (cost=9952.15..12638126.98 rows=572635 width=12)
               Outer Scan: flineorder  (cost=9877.70..12649677.69 rows=4010017 width=16)
               Outer Scan Filter: ((lo_discount &gt;= 1) AND (lo_discount &lt;= 3) AND (lo_quantity &lt; 25))
               Depth 1: GpuHashJoin  (nrows 4010017...572635)
                        HashKeys: flineorder.lo_orderdate
                        JoinQuals: (flineorder.lo_orderdate = date1.d_datekey)
                        KDS-Hash (size: 66.06KB)
               GPU Preference: GPU0 (Tesla V100-PCIE-16GB)
               NVMe-Strom: enabled
               referenced: lo_orderdate, lo_quantity, lo_extendedprice, lo_discount
               files0: /opt/nvme/lineorder_s401.arrow (size: 309.23GB)
               -&gt;  Seq Scan on date1  (cost=0.00..78.95 rows=365 width=4)
                     Filter: (d_year = 1993)
(18 rows)
</code></pre>

<p>これを見るとCustom Scan (GpuJoin)が<code>flineorder</code>外部テーブルをスキャンしている事がわかります。 <code>file0</code>には外部テーブルの背後にあるファイル名<code>/opt/nvme/lineorder_s401.arrow</code>とそのサイズが表示されます。複数のファイルがマップされている場合には、<code>file1</code>、<code>file2</code>、... と各ファイル毎に表示されます。 <code>referenced</code>には実際に参照されている列の一覧が列挙されており、このクエリにおいては<code>lo_orderdate</code>、<code>lo_quantity</code>、<code>lo_extendedprice</code>および<code>lo_discount</code>列が参照されている事がわかります。</p>
<p>また、<code>GPU Preference: GPU0 (Tesla V100-PCIE-16GB)</code>および<code>NVMe-Strom: enabled</code>の表示がある事から、<code>flineorder</code>のスキャンにはSSD-to-GPUダイレクトSQL機構が用いられることが分かります。</p>
<p>VERBOSEオプションを付与する事で、より詳細な情報が出力されます。</p>
<pre><code>=# EXPLAIN VERBOSE
    SELECT sum(lo_extendedprice*lo_discount) as revenue
      FROM flineorder,date1
     WHERE lo_orderdate = d_datekey
       AND d_year = 1993
       AND lo_discount between 1 and 3
       AND lo_quantity &lt; 25;
                              QUERY PLAN
--------------------------------------------------------------------------------
 Aggregate  (cost=12632759.02..12632759.03 rows=1 width=32)
   Output: sum((pgstrom.psum((flineorder.lo_extendedprice * flineorder.lo_discount))))
   -&gt;  Custom Scan (GpuPreAgg)  (cost=12632754.43..12632757.49 rows=204 width=8)
         Output: (pgstrom.psum((flineorder.lo_extendedprice * flineorder.lo_discount)))
         Reduction: NoGroup
         GPU Projection: flineorder.lo_extendedprice, flineorder.lo_discount, pgstrom.psum((flineorder.lo_extendedprice * flineorder.lo_discount))
         Combined GpuJoin: enabled
         GPU Preference: GPU0 (Tesla V100-PCIE-16GB)
         -&gt;  Custom Scan (GpuJoin) on public.flineorder  (cost=9952.15..12638126.98 rows=572635 width=12)
               Output: flineorder.lo_extendedprice, flineorder.lo_discount
               GPU Projection: flineorder.lo_extendedprice::bigint, flineorder.lo_discount::integer
               Outer Scan: public.flineorder  (cost=9877.70..12649677.69 rows=4010017 width=16)
               Outer Scan Filter: ((flineorder.lo_discount &gt;= 1) AND (flineorder.lo_discount &lt;= 3) AND (flineorder.lo_quantity &lt; 25))
               Depth 1: GpuHashJoin  (nrows 4010017...572635)
                        HashKeys: flineorder.lo_orderdate
                        JoinQuals: (flineorder.lo_orderdate = date1.d_datekey)
                        KDS-Hash (size: 66.06KB)
               GPU Preference: GPU0 (Tesla V100-PCIE-16GB)
               NVMe-Strom: enabled
               referenced: lo_orderdate, lo_quantity, lo_extendedprice, lo_discount
               files0: /opt/nvme/lineorder_s401.arrow (size: 309.23GB)
                 lo_orderpriority: 33.61GB
                 lo_extendedprice: 17.93GB
                 lo_ordertotalprice: 17.93GB
                 lo_revenue: 17.93GB
               -&gt;  Seq Scan on public.date1  (cost=0.00..78.95 rows=365 width=4)
                     Output: date1.d_datekey
                     Filter: (date1.d_year = 1993)
(28 rows)
</code></pre>

<p>被参照列をロードする際に読み出すべき列データの大きさを、列ごとに表示しています。 <code>lo_orderdate</code>、<code>lo_quantity</code>、<code>lo_extendedprice</code>および<code>lo_discount</code>列のロードには合計で87.4GBの読み出しが必要で、これはファイルサイズ309.2GBの28.3%に相当します。</p>
<h1 id="arrow">Arrowファイルの作成方法</h1>
<p>本節では、既にPostgreSQLデータベースに格納されているデータをApache Arrow形式に変換する方法を説明します。</p>
<h2 id="pyarrowpandas">PyArrow+Pandas</h2>
<p>Arrow開発者コミュニティが開発を行っている PyArrow モジュールとPandasデータフレームの組合せを用いて、PostgreSQLデータベースの内容をArrow形式ファイルへと書き出す事ができます。</p>
<p>以下の例は、テーブルt0に格納されたデータを全て読込み、ファイル/tmp/t0.arrowへと書き出すというものです。</p>
<pre><code>import pyarrow as pa
import pandas as pd

X = pd.read_sql(sql=&quot;SELECT * FROM t0&quot;, con=&quot;postgresql://localhost/postgres&quot;)
Y = pa.Table.from_pandas(X)
f = pa.RecordBatchFileWriter('/tmp/t0.arrow', Y.schema)
f.write_table(Y,1000000)      # RecordBatch for each million rows
f.close()
</code></pre>

<p>ただし上記の方法は、SQLを介してPostgreSQLから読み出したデータベースの内容を一度メモリに保持するため、大量の行を一度に変換する場合には注意が必要です。</p>
<h2 id="pg2arrow">Pg2Arrow</h2>
<p>一方、PG-Strom Development Teamが開発を行っている <code>pg2arrow</code> コマンドを使用して、PostgreSQLデータベースの内容をArrow形式ファイルへと書き出す事ができます。 このツールは比較的大量のデータをNVME-SSDなどストレージに書き出す事を念頭に設計されており、PostgreSQLデータベースから<code>-s|--segment-size</code>オプションで指定したサイズのデータを読み出すたびに、Arrow形式のレコードバッチ（Record Batch）としてファイルに書き出します。そのため、メモリ消費量は比較的リーズナブルな値となります。</p>
<p><code>pg2arrow</code>コマンドはPG-Stromに同梱されており、PostgreSQL関連コマンドのインストール先ディレクトリに格納されます。</p>
<pre><code>$ pg2arrow --help
Usage:
  pg2arrow [OPTION]... [DBNAME [USERNAME]]

General options:
  -d, --dbname=DBNAME     database name to connect to
  -c, --command=COMMAND   SQL command to run
  -f, --file=FILENAME     SQL command from file
      (-c and -f are exclusive, either of them must be specified)
  -o, --output=FILENAME   result file in Apache Arrow format
      (default creates a temporary file)

Arrow format options:
  -s, --segment-size=SIZE size of record batch for each
      (default: 256MB)

Connection options:
  -h, --host=HOSTNAME     database server host
  -p, --port=PORT         database server port
  -U, --username=USERNAME database user name
  -w, --no-password       never prompt for password
  -W, --password          force password prompt

Debug options:
      --dump=FILENAME     dump information of arrow file
      --progress          shows progress of the job.

Report bugs to &lt;pgstrom@heterodbcom.
</code></pre>

<p>PostgreSQLへの接続パラメータはpsqlやpg_dumpと同様に、<code>-h</code>や<code>-U</code>などのオプションで指定します。 基本的なコマンドの使用方法は、<code>-c|--command</code>オプションで指定したSQLをPostgreSQL上で実行し、その結果を<code>-o|--output</code>で指定したファイルへArrow形式で書き出します。</p>
<p>以下の例は、テーブル<code>t0</code>に格納されたデータを全て読込み、ファイル<code>/tmp/t0.arrow</code>へと書き出すというものです。</p>
<pre><code>$ pg2arrow -U kaigai -d postgres -c &quot;SELECT * FROM t0&quot; -o /tmp/t0.arrow
</code></pre>

<p>開発者向けオプションですが、<code>--dump &lt;filename&gt;</code>でArrow形式ファイルのスキーマ定義やレコードバッチの位置とサイズを可読な形式で出力する事もできます。</p>
<h1 id="_6">先進的な使い方</h1>
<h2 id="ssdtogpusql">SSDtoGPUダイレクトSQL</h2>
<p>Arrow_Fdw外部テーブルにマップされた全てのArrow形式ファイルが以下の条件を満たす場合には、列データの読み出しにSSD-to-GPUダイレクトSQLを使用する事ができます。</p>
<ul>
<li>Arrow形式ファイルがNVME-SSD区画上に置かれている。</li>
<li>NVME-SSD区画はExt4ファイルシステムで構築されている。</li>
<li>Arrow形式ファイルの総計が<code>pg_strom.nvme_strom_threshold</code>設定を上回っている。</li>
</ul>
<h2 id="_7">パーティション設定</h2>
<p>Arrow_Fdw外部テーブルを、パーティションの一部として利用する事ができます。 通常のPostgreSQLテーブルと混在する事も可能ですが、Arrow_Fdw外部テーブルは書き込みに対応していない事に注意してください。 また、マップされたArrow形式ファイルに含まれるデータは、パーティションの境界条件と矛盾しないように設定してください。これはデータベース管理者の責任です。</p>
<p><img alt="Example of partition configuration" src="../img/partition-logdata.png" /></p>
<p>典型的な利用シーンは、長期間にわたり蓄積したログデータの処理です。</p>
<p>トランザクションデータと異なり、一般的にログデータは一度記録されたらその後更新削除されることはありません。 したがって、一定期間が経過したログデータは、読み出し専用ではあるものの集計処理が高速なArrow_Fdw外部テーブルに移し替えることで、集計・解析ワークロードの処理効率を引き上げる事が可能となります。また、ログデータにはほぼ間違いなくタイムスタンプが付与されている事から、月単位、週単位など、一定期間ごとにパーティション子テーブルを追加する事が可能です。</p>
<p>以下の例は、PostgreSQLテーブルとArrow_Fdw外部テーブルを混在させたパーティションテーブルを定義したものです。</p>
<p>書き込みが可能なPostgreSQLテーブルをデフォルトパーティションとして指定しておく<sup id="fnref:2"><a class="footnote-ref" href="#fn:2" rel="footnote">2</a></sup>事で、一定期間の経過後、DB運用を継続しながら過去のログデータだけをArrow_Fdw外部テーブルへ移す事が可能です。</p>
<pre><code>CREATE TABLE lineorder (
    lo_orderkey numeric,
    lo_linenumber integer,
    lo_custkey numeric,
    lo_partkey integer,
    lo_suppkey numeric,
    lo_orderdate integer,
    lo_orderpriority character(15),
    lo_shippriority character(1),
    lo_quantity numeric,
    lo_extendedprice numeric,
    lo_ordertotalprice numeric,
    lo_discount numeric,
    lo_revenue numeric,
    lo_supplycost numeric,
    lo_tax numeric,
    lo_commit_date character(8),
    lo_shipmode character(10)
) PARTITION BY RANGE (lo_orderdate);

CREATE TABLE lineorder__now PARTITION OF lineorder default;

CREATE FOREIGN TABLE lineorder__1993 PARTITION OF lineorder
   FOR VALUES FROM (19930101) TO (19940101)
SERVER arrow_fdw OPTIONS (file '/opt/tmp/lineorder_1993.arrow');

CREATE FOREIGN TABLE lineorder__1994 PARTITION OF lineorder
   FOR VALUES FROM (19940101) TO (19950101)
SERVER arrow_fdw OPTIONS (file '/opt/tmp/lineorder_1994.arrow');

CREATE FOREIGN TABLE lineorder__1995 PARTITION OF lineorder
   FOR VALUES FROM (19950101) TO (19960101)
SERVER arrow_fdw OPTIONS (file '/opt/tmp/lineorder_1995.arrow');

CREATE FOREIGN TABLE lineorder__1996 PARTITION OF lineorder
   FOR VALUES FROM (19960101) TO (19970101)
SERVER arrow_fdw OPTIONS (file '/opt/tmp/lineorder_1996.arrow');
</code></pre>

<p>このテーブルに対する問い合わせの実行計画は以下のようになります。 検索条件<code>lo_orderdate between 19950701 and 19960630</code>がパーティションの境界条件を含んでいる事から、子テーブル<code>lineorder__1993</code>と<code>lineorder__1994</code>は検索対象から排除され、他のテーブルだけを読み出すよう実行計画が作られています。</p>
<pre><code>=# EXPLAIN
    SELECT sum(lo_extendedprice*lo_discount) as revenue
      FROM lineorder,date1
     WHERE lo_orderdate = d_datekey
       AND lo_orderdate between 19950701 and 19960630
       AND lo_discount between 1 and 3
       ABD lo_quantity &lt; 25;

                                 QUERY PLAN
--------------------------------------------------------------------------------
 Aggregate  (cost=172088.90..172088.91 rows=1 width=32)
   -&gt;  Hash Join  (cost=10548.86..172088.51 rows=77 width=64)
         Hash Cond: (lineorder__1995.lo_orderdate = date1.d_datekey)
         -&gt;  Append  (cost=10444.35..171983.80 rows=77 width=67)
               -&gt;  Custom Scan (GpuScan) on lineorder__1995  (cost=10444.35..33671.87 rows=38 width=68)
                     GPU Filter: ((lo_orderdate &gt;= 19950701) AND (lo_orderdate &lt;= 19960630) AND
                                  (lo_discount &gt;= '1'::numeric) AND (lo_discount &lt;= '3'::numeric) AND
                                  (lo_quantity &lt; '25'::numeric))
                     referenced: lo_orderdate, lo_quantity, lo_extendedprice, lo_discount
                     files0: /opt/tmp/lineorder_1995.arrow (size: 892.57MB)
               -&gt;  Custom Scan (GpuScan) on lineorder__1996  (cost=10444.62..33849.21 rows=38 width=68)
                     GPU Filter: ((lo_orderdate &gt;= 19950701) AND (lo_orderdate &lt;= 19960630) AND
                                  (lo_discount &gt;= '1'::numeric) AND (lo_discount &lt;= '3'::numeric) AND
                                  (lo_quantity &lt; '25'::numeric))
                     referenced: lo_orderdate, lo_quantity, lo_extendedprice, lo_discount
                     files0: /opt/tmp/lineorder_1996.arrow (size: 897.87MB)
               -&gt;  Custom Scan (GpuScan) on lineorder__now  (cost=11561.33..104462.33 rows=1 width=18)
                     GPU Filter: ((lo_orderdate &gt;= 19950701) AND (lo_orderdate &lt;= 19960630) AND
                                  (lo_discount &gt;= '1'::numeric) AND (lo_discount &lt;= '3'::numeric) AND
                                  (lo_quantity &lt; '25'::numeric))
         -&gt;  Hash  (cost=72.56..72.56 rows=2556 width=4)
               -&gt;  Seq Scan on date1  (cost=0.00..72.56 rows=2556 width=4)
(16 rows)

</code></pre>

<p>この後、<code>lineorder__now</code>テーブルから1997年のデータを抜き出し、これをArrow_Fdw外部テーブル側に移すには以下の操作を行います</p>
<pre><code>$ pg2arrow -d sample  -o /opt/tmp/lineorder_1997.arrow \
           -c &quot;SELECT * FROM lineorder WHERE lo_orderdate between 19970101 and 19971231&quot;
</code></pre>

<p><code>pg2arrow</code>コマンドにより、<code>lineorder</code>テーブルから1997年のデータだけを抜き出して、新しいArrow形式ファイルへ書き出します。</p>
<pre><code>BEGIN;
--
-- remove rows in 1997 from the read-writable table
--
DELETE FROM lineorder WHERE lo_orderdate BETWEEN 19970101 AND 19971231;
--
-- define a new partition leaf which maps log-data in 1997
--
CREATE FOREIGN TABLE lineorder__1997 PARTITION OF lineorder
   FOR VALUES FROM (19970101) TO (19980101)
SERVER arrow_fdw OPTIONS (file '/opt/tmp/lineorder_1997.arrow');

COMMIT;
</code></pre>

<p>この操作により、PostgreSQLテーブルである<code>lineorder__now</code>から1997年のデータを削除し、代わりに同一内容のArrow形式ファイル<code>/opt/tmp/lineorder_1997.arrow</code>を外部テーブル<code>lineorder__1997</code>としてマップしました。</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:1">
<p>正確には、4KB～32KBの範囲でビルド時に指定できます&#160;<a class="footnote-backref" href="#fnref:1" rev="footnote" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>
<li id="fn:2">
<p>PostgreSQL v11以降で対応&#160;<a class="footnote-backref" href="#fnref:2" rev="footnote" title="Jump back to footnote 2 in the text">&#8617;</a></p>
</li>
</ol>
</div>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="../gstore_fdw/" class="btn btn-neutral float-right" title="Gstore_fdw">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
        <a href="../ssd2gpu/" class="btn btn-neutral" title="SSDtoGPUダイレクトSQL"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
      
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
      
        <span><a href="../ssd2gpu/" style="color: #fcfcfc;">&laquo; Previous</a></span>
      
      
        <span style="margin-left: 15px"><a href="../gstore_fdw/" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>
    <script>var base_url = '..';</script>
    <script src="../js/theme.js" defer></script>
      <script src="../search/main.js" defer></script>

</body>
</html>
